Crate chbs

Expand description

Note: this crate is still a work in progress, APIs might change until stabilisation

A secure, easy to use, configurable and extendable passphrase generation library based on a wordlist, generally known as diceware.

The crate name chbs is short for the well known “correct horse battery staple” password which originates from an XKCD comic shown in the README here.

This library uses cryptographically secure randomization, and may be used for generating secret passphrases. Please refer to the README for more information on security.

Concepts

As the passphrase generation system in this crate is thoroughly abstracted it is important to understand how the concepts used in this crate work.

Here is what is required for passphrase generation:

A Scheme defines how a passphrase is generated. Passphrases are only generated through a scheme.
A Scheme contains components which represents how the passphrase is built up and styled. Four kinds of components exist, defining the passphrase generation steps. For some kinds one must be defined, for other kinds any number is fine:
1. WordSetProvider (1 required): provides a list of words to use in a passphrase.
2. WordStyler (>=0 required): styles passphrase words, for example, to capitalize.
3. PhraseBuilder (1 required): builds a phrase from a set of passphrase words.
4. PhraseStyler (>=0 required): styles a whole passphrase.

Things to understand:

Passphrase generation schemes are commonly created by using a configuration structure. Such as structure will provide various configurable fields, and builds a corresponding scheme based on it for passphrase generation.

The usual steps for generating a passphrase:

A configuration structure is built and configured, such as BasicConfig.
The configuration struct creates a corresponding passphrase generation scheme.
The scheme is used to generate as many passphrases as needed.
Instead, the passphrase() helper method may be used to generate a passphrase with zero configuration for ease of use.

See, it isn’t too difficult, but allows great extensibility. You probably won’t use most of what this crate provides.
Take a look at BasicConfig to see how to configure your first passphrase generator.

Additional good-to-know things:

This crate provides a selection of components for specific tasks, custom components may be built.
This crate provides a WordList struct to hold a static wordlist, that may use a built-in wordlist or loads a wordlist from a specified file.
A WordSampler may be constructed based on a WordList to allow randomized word sampling in an uniform manner. Such a sampler is usually what is used as word provider in a configuration struct.

Examples

Here are two very basic examples. First to generate a passphrase with zero configuration using a helper function applying library defaults (src):

use chbs::passphrase;

println!("Passphrase: {:?}", passphrase());

Generating a passphrase with configuration is recommended, here is a basic example (src):

use chbs::{config::BasicConfig, prelude::*, probability::Probability};

// Build a custom configuration to:
let mut config = BasicConfig::default();
config.words = 8;
config.separator = "-".into();
config.capitalize_first = Probability::from(0.33);
config.capitalize_words = Probability::half();
let mut scheme = config.to_scheme();

println!("Passphrase: {:?}", scheme.generate());
println!("Entropy: {:?}", scheme.entropy().bits());